home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d17 / prform17.arc / PRFORM.DOC < prev    next >
Text File  |  1988-06-16  |  17KB  |  397 lines
  1.      
  2.      
  3.      
  4.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  5.      
  6.      
  7.      
  8.      NAME
  9.           PRFORM - A PRintout FORMatter in C
  10.      
  11.      SYNOPSIS
  12.           PRFORM is invoked by a command line of the following form:
  13.      
  14.                prform [[-option -option ...] file1 file2 ...] ...
  15.      
  16.                                      - or -
  17.      
  18.                           prform [-option -option ...]
  19.      
  20.           where the options preceeding each group of files specify the
  21.           format  of the output for that group of files.  In the first
  22.           form, PRFORM acts on the  specified  files;  in  the  second
  23.           form, PRFORM acts on standard input.
  24.      
  25.           Options are:
  26.      
  27.             -a       as-is output (expand tabs and page breaks only)
  28.             -e#      end printing after the #th page
  29.             -E       no ending line number in page count
  30.             -hfMprt  sets the page heading
  31.                f   places the file name into the page heading
  32.                M   places the header message (defined by -M)
  33.                     into the page heading
  34.                p   places the page number into the page heading
  35.                r   places the rest of the heading on the right side
  36.                t   places the date and time into the page heading
  37.                    no option after h sets no page heading
  38.                     (default option sequence is frp)
  39.             -hefMprt sets the page heading for even pages
  40.                     (default option sequence is )
  41.             -hofMprt sets the page heading for odd pages
  42.                     (default option sequence is )
  43.             -H       prints this help message on stderr and exits
  44.             -l#      is the length of a line (def 80)
  45.             -m#      is the length of the left margin (def 5)
  46.             -M<text> sets the header message to <text>
  47.             -n       causes each line to be numbered (-M set to 8)
  48.             -o<name> redirects the output listing to the indicated file
  49.             -p#      is the number of lines/page (def 62)
  50.             -s#      start printing at the #th page (def 1)
  51.                     (note: also does -S#, setting first page number)
  52.             -S#      sets the number of the first printed page
  53.             -t#      is the number of columns per tab stop (def 8)
  54.             -T       truncate lines which are too long
  55.      
  56.      
  57.      DESCRIPTION
  58.           PRFORM generates a formatted listing of  one  or  more  text
  59.           files.   The listing can include features such as headers at
  60.      
  61.      
  62.      
  63.      Sun Release 3.2     Last change: 16 June 1988                   1
  64.      
  65.      
  66.      
  67.      
  68.      
  69.      
  70.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  71.      
  72.      
  73.      
  74.           the top of each page, numbers in front of  each  line,  wra-
  75.           paround  if  lines  exceed  the width of a page, page breaks
  76.           after an indicated number of lines, etc.   The  listing  can
  77.           start on a specified page if desired.  PRFORM sends its out-
  78.           put to either standard output (default) or a text file.
  79.      
  80.           PRFORM functions as either a conventional program,  process-
  81.           ing  files  specified  on  its command line, or as a filter,
  82.           obtaining its input from standard input.  If  no  files  are
  83.           specified  on  the command line (only zero or more options),
  84.           then PRFORM inputs from standard input.
  85.      
  86.           Most of the options to PRFORM  are  self-explanatory.   Each
  87.           group  of  options  encountered in the command line causes a
  88.           reset to the default options and then a setting of the indi-
  89.           cated  options,  so previous options selections are overrid-
  90.           den; example:
  91.      
  92.                prform -a -m5 file1 -m0 file2
  93.                       \____/       \_/
  94.                      Group 1      Group 2
  95.      
  96.                file1 is printed as-is with a 5-char margin
  97.                file2 is printed with all defaults and no margin
  98.      
  99.      
  100.      
  101.      
  102.                                     _A_s-_I_s _O_u_t_p_u_t
  103.      
  104.           The -a option causes the  file  to  be  output  as-is.   All
  105.           option are set by this command to the following values:
  106.      
  107.                Lines are not truncated.
  108.      
  109.                No heading is output (default heading, even-page  head-
  110.                ing, and odd-page heading are cleared).
  111.      
  112.                Line length is set to the maximum allowed for the  pro-
  113.                gram (400 characters).
  114.      
  115.                Left margin is set to zero.
  116.      
  117.                Line numbering is turned off.
  118.      
  119.                Number of lines per page is set to zero (no paging).
  120.      
  121.                Starting page is set to 1.
  122.      
  123.                Tab stops are set to every 8.
  124.      
  125.      
  126.      
  127.      
  128.      
  129.      Sun Release 3.2     Last change: 16 June 1988                   2
  130.      
  131.      
  132.      
  133.      
  134.      
  135.      
  136.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  137.      
  138.      
  139.      
  140.           The -a option can be followed by other options, such as -m#,
  141.           to set a bare output with the exception of some minimum pro-
  142.           cessing (such as a left margin).
  143.      
  144.      
  145.      
  146.                          _L_i_n_e _W_r_a_p_a_r_o_u_n_d _a_n_d _T_r_u_n_c_a_t_i_o_n
  147.      
  148.           If the length of a line exceeds  the  number  of  characters
  149.           specified  by the -l (ell) option or its default value, that
  150.           line will either wrap around to the next line of  the  prin-
  151.           tout  or  be  truncated.  If the -T option is specified, the
  152.           line will be truncated; if not, the line will  wrap  around,
  153.           and  the  continuation  line is prefixed by two greater than
  154.           signs (>>) on the far left.
  155.      
  156.             -_l_7_0 sets the line length to 70 characters total  (includ-
  157.                ing the left margin).
  158.      
  159.             -_l_7_0 -_m_1_0 sets the line length to 70  characters  and  the
  160.                left margin to 10.  There is a maximum of 60 characters
  161.                in each output line.
  162.      
  163.             -_T -_l_5_0 sets the line length to 50 characters and  enables
  164.                truncation  of  any  characters beyond column 50 in the
  165.                generated listing.
  166.      
  167.      
  168.      
  169.                          _P_a_g_e _R_a_n_g_e_s _a_n_d _P_a_g_e _N_u_m_b_e_r_i_n_g
  170.      
  171.           The -s# and -e# commands set the starting  and  ending  page
  172.           boundaries.   If  the  -s#  command is not given, the output
  173.           starts at the first page.  If the -e# command is not  given,
  174.           the  output  ends  at the last page.  The arguments to these
  175.           commands are absolute page numbers, indicating the nth  phy-
  176.           sical  page  in  the listing.  This is as opposed to the -S#
  177.           command.
  178.      
  179.           The -S# command sets the number of  the  first  page  to  be
  180.           printed.   If  the  -S# command is not given, this number is
  181.           the same as the absolute number of the  first  printed  page
  182.           (same  as  the number given in the -s# command).  The number
  183.           given by the -S# command is the number that appears  in  the
  184.           page  heading  for  the  first  page  printed, and each page
  185.           printed after that is incremented from this starting number.
  186.      
  187.           The -E command causes the page numbers printed in the  head-
  188.           ing  to  omit the " of n" part of the output (eg, without -E
  189.           the heading contains "Page 1 of 5", but with -E the  heading
  190.           contains "Page 1").
  191.      
  192.      
  193.      
  194.      
  195.      Sun Release 3.2     Last change: 16 June 1988                   3
  196.      
  197.      
  198.      
  199.      
  200.      
  201.      
  202.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  203.      
  204.      
  205.      
  206.             -_s_5 -_e_7 causes  the  5th  through  the  7th  pages  to  be
  207.                printed.
  208.      
  209.             -_s_1_0 -_e_2_0 -_S_1 causes the 10th through the 20th pages to be
  210.                printed, and the 10th page is numbered 1, the 11th page
  211.                is 2, etc., to the 20th page, which is numbered 11.
  212.      
  213.             -_s_1_0 -_e_2_0 -_E_S_1 is  the  same  as  above  except  the  page
  214.                headers do not contain the number of the last page (the
  215.                " of n" part is omitted from the page number).
  216.      
  217.      
  218.      
  219.      
  220.                                  _P_a_g_e _H_e_a_d_i_n_g_s
  221.      
  222.           The heading options provide for a declaration of  a  general
  223.           page heading, a heading for even-numbered pages, and a head-
  224.           ing for odd-numbered pages.  If a heading for  even-numbered
  225.           pages  is  not  specified, the general page heading is used;
  226.           likewise for odd-numbered pages.
  227.      
  228.           A heading can consist of up to four components: the name  of
  229.           the file (f option), some user-specified message (M option),
  230.           the page number (p option), and the date  and  time  of  the
  231.           printout (t option).  The user-specified message is provided
  232.           by the -M option; example:
  233.      
  234.                             "-Mmy heading text" -hM
  235.      
  236.           sets "my heading text" as  the  user-specified  message  and
  237.           sets  the  header  to  output only that text.  Each selected
  238.           component (except for the user-specified  message)  is  fol-
  239.           lowed  by  four  spaces  so that the selected components are
  240.           separated from each other.  An r option is also available to
  241.           make  the  components  following  this  option  to be right-
  242.           justified on the heading line.  For example:
  243.      
  244.             -_M_L_i_s_t_i_n_g -_h_p_f_M places the page  number  followed  by  the
  245.                file  name  followed  by the text "Listing" on the left
  246.                side of the  heading  line.   All  pages  are  affected
  247.                unless an -he or -ho option is specified.
  248.      
  249.             "-_M_I_m_p_o_r_t_a_n_t _L_i_s_t_i_n_g" -_h_f_M_r_p places the file name followed
  250.                by the text "Important Listing" on the left side of the
  251.                heading line and the page  number  on  the  right  side
  252.                (justified  against  the  right margin).  All pages are
  253.                affected unless an -he  or  -ho  option  is  specified.
  254.                Note  the  use of quotes to enclose the -M<text> string
  255.                when spaces are to be included in the <text>.
  256.      
  257.             -_h_o_f_r_p -_h_e_p_r_f places (1) the file name on  the  left  side
  258.      
  259.      
  260.      
  261.      Sun Release 3.2     Last change: 16 June 1988                   4
  262.      
  263.      
  264.      
  265.      
  266.      
  267.      
  268.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  269.      
  270.      
  271.      
  272.                and  the  page number on the right side of odd-numbered
  273.                pages and (2) the page number on the left side and  the
  274.                file name on the right side of even-numbered pages.
  275.      
  276.             -_h_o_f_r_t_p -_h_e_p_t_r_f places (1) the file name on the left  side
  277.                and  the  date  and time followed by the page number on
  278.                the right side of odd-numbered pages and (2)  the  page
  279.                number  followed  by the date and time on the left side
  280.                and the file name on the right  side  of  even-numbered
  281.                pages.
  282.      
  283.      
  284.           See also the -E option in the previous section.
  285.      
  286.      
  287.      EXAMPLE
  288.             _p_r_f_o_r_m -_h_o_f_r_p -_h_e_p_r_f -_l_6_0 _m_y_f_i_l_e._t_x_t -_h_f_r_p -_t_3 _t_e_s_t._c out-
  289.                puts  (1)  "myfile.txt"  with  the default values, odd-
  290.                numbered pages containing heading lines  consisting  of
  291.                the  file  name  on the left and the page number on the
  292.                right, even-numbered  pages  containing  heading  lines
  293.                consisting  of the page number on the left and the file
  294.                name on the right, and 60  characters  in  each  output
  295.                line  and (2) "test.c" with the default values (includ-
  296.                ing 80 characters in each output line),  heading  lines
  297.                on  both odd- and even-numbered pages consisting of the
  298.                file name on the left and the page number on the right,
  299.                and  tab stops at every 3 columns (note that the second
  300.                group of options reset all previous option settings).
  301.      
  302.             _p_r_f_o_r_m "-_M_C _P_r_o_g_r_a_m_s: " -_h_M_f_r_p *._c | _l_p_r outputs all files
  303.                matching  "*.c"  to  standard output, which is piped to
  304.                the line printer spooler.  A form feed is placed  after
  305.                each  file, and page and line numbered start fresh with
  306.                each file.  The user-specified heading text is  set  to
  307.                "C  Programs:  "  and  the page headings consist of the
  308.                user-specified message followed by the file name on the
  309.                left  and  the page number on the right.  Note that the
  310.                trailing space after the colon of the  heading  message
  311.                was placed there because the message is the only param-
  312.                eter in the -h option list which  is  not  followed  by
  313.                four spaces.
  314.      
  315.             _n_r_o_f_f -_m_a_n _f_i_l_e._1 | _p_r_f_o_r_m -_a -_m_5  |  _l_p_r  runs  nroff  on
  316.                file.1,  pipes the output from nroff into prform (which
  317.                outputs it as-is was a left margin of 5 spaces  added),
  318.                and  pipes  the  prform output to the lpr program.  The
  319.                net effect of this command is to  print  the  formatted
  320.                file.1 with a left margin of 5 spaces on each line.
  321.      
  322.      
  323.      
  324.      
  325.      
  326.      
  327.      Sun Release 3.2     Last change: 16 June 1988                   5
  328.      
  329.      
  330.      
  331.      
  332.      
  333.      
  334.      PRFORM(1)                 USER COMMANDS                 PRFORM(1)
  335.      
  336.      
  337.      
  338.      FILES
  339.           prform - executable
  340.      
  341.           prform.c - source
  342.      
  343.           prform.l - man file
  344.      
  345.           /tmp/prform# - temporary file created when input is provided
  346.           on  standard  input  rather than from a specified file (this
  347.           file is deleted from  /tmp  when  prform  successfully  com-
  348.           pletes)
  349.      
  350.      
  351.      DIAGNOSTICS
  352.             _C_a_n_n_o_t _O_p_e_n _O_u_t_p_u_t _F_i_l_e  <_f_i_l_e_n_a_m_e>  is  issued  when  the
  353.                -ffilename option is specified and the output file can-
  354.                not be created for some reason.  This is a fatal error,
  355.                causing the program to abort.
  356.      
  357.             _C_a_n_n_o_t _C_r_e_a_t_e _T_e_m_p_o_r_a_r_y _F_i_l_e <_f_i_l_e_n_a_m_e> is issued with the
  358.                input  to PRFORM is obtained from standard input and it
  359.                cannot create the copy of the input in the /tmp/prform*
  360.                file for some reason (out of space in /tmp, etc.).
  361.      
  362.             _C_a_n_n_o_t _O_p_e_n  <_f_i_l_e_n_a_m_e>  or  _C_a_n_n_o_t  _O_p_e_n  _T_e_m_p_o_r_a_r_y  _F_i_l_e
  363.                <_f_i_l_e_n_a_m_e>  is  issued  when  PRFORM  is  beginning its
  364.                second pass and cannot open the input file.
  365.      
  366.             _I_n_v_a_l_i_d _O_p_t_i_o_n _a_t <_t_e_x_t> is issued when an invalid  option
  367.                is  encountered  on  the command line.  The text starts
  368.                with the invalid option character.   This  is  a  fatal
  369.                error, causing the program to abort.
  370.      
  371.      
  372.      
  373.      BUGS
  374.           Input and output line lengths should not exceed 400  charac-
  375.           ters.
  376.      
  377.      
  378.      AUTHOR
  379.           PRFORM Version 1.x (Beta Test) was written by Richard Conn.
  380.      
  381.      
  382.      
  383.      
  384.      
  385.      
  386.      
  387.      
  388.      
  389.      
  390.      
  391.      
  392.      
  393.      Sun Release 3.2     Last change: 16 June 1988                   6
  394.      
  395.      
  396.      
  397.